<html>
<!--
 Copyright (C) 2005, 2006 Joe Walnes.
 Copyright (C) 2006, 2007, 2021 XStream committers.
 All rights reserved.
 
 The software in this package is published under the terms of the BSD
 style license a copy of which has been included with this distribution in
 the LICENSE.txt file.
 
 Created on 29. January 2005 by Joe Walnes
 -->
    <head>
        <title>Architecture Overview</title>
    </head>
    <body>

        <p>The architecture of XStream consists of the six main components:</p>

        <ul>
            <li><b>Converters</b></li>
            <li><b>Mappers</b></li>
            <li><b>Drivers (Writer and Reader)</b></li>
            <li><b>Context</b></li>
            <li><b>Type Permissions</b></li>
            <li><b>Facade</b></li>
        </ul>

        <!-- ************ -->

        <h1 id="LifeCycle">Life Cycle</h1>

        <p>An XStream instance envisages two phases in its life cycle: Setup and Execution.  A lot of default configuration is
        already applied when an XStream instance is instantiated, i.e. the instance is directly in setup phase.  Now is
        the time to apply further configuration.  This phase is not  thread-safe.</p>

        <p>Once an instance is properly configured in can be used in an execution phase, where
        <a href="graphs.html">Java object graphs</a> are marshalled and unmarshalled.  The execution phase is
        thread-safe, i.e. is is possible to use an XStream instance concurrently for execution.  However, XStream
        builds caches during execution based on the configuration.  Therefore, an instance should never be reconfigured
        during or after execution phase.  The result of any further (un-)marshalling might not be what is expected.</p>

        <!-- ************ -->

        <h1 id="Converters">Converters</h1>

        <p>Whenever XStream encounters an object that needs to be converted to/from XML, it delegates to a suitable
        <a href="javadoc/com/thoughtworks/xstream/converters/Converter.html">Converter</a> implementation associated
        with the class of that Object.</p>

        <p>XStream comes <a href="converters.html">bundled with many converters</a> for common types, including primitives,
        String, Collections, arrays, null, Date, etc.</p>

        <p>XStream also has a <i>default Converter</i>, that is used when no other Converters match a type.  This uses
        reflection to automatically generate the XML for all the fields in an object.</p>

        <p>If an object is composed of other objects, the Converter may delegate to other Converters.</p>

        <p class="highlight">To customize the XML for particular object type a new Converter should be implemented.</p>

        <!-- ************ -->

        <h1 id="Mappers">Mappers</h1>

        <p><a href="javadoc/com/thoughtworks/xstream/mapper/Mapper.html">Mapper</a> implementations are the key
        components to map between names used in XML and names of Java elements and vice versa.  Mappers are organized
        in a chain, e.g. every time a mapper cannot map a special name it delegates the call to its logical parent.
        Mappers keep the configuration in XStream and a converter should always use the Mapper (chain) of XStream to
        map names it has to deal with.</p>

        <p>XStream comes bundled with many mappers to map names of ordinary Java types and elements, of arrays, enums,
        proxies, outer classes, to handle alias definitions, implicit collections, and ignored elements and even the
        <a href="security.html#framework">Security Framework</a> is based on a Mapper implementation.</p>

        <p class="highlight">Overwrite XStream's <em>wrapMapper</em> function to add custom mapper implementation.</p>

        <!-- ************ -->

        <h1 id="Drivers">Drivers (Writer and Reader)</h1>

        <p>XStream is abstracted from the underlying XML data using the
        <a href="javadoc/com/thoughtworks/xstream/io/HierarchicalStreamWriter.html">HierarchicalStreamWriter</a>
        and <a href="javadoc/com/thoughtworks/xstream/io/HierarchicalStreamReader.html">HierarchicalStreamReader</a>
        interfaces for serializing and deserializing respectively.</p>

        <p>This abstraction allows XStream to read XML from direct streams using an XML parser or directly manipulate
        existing structures (such as DOM). This prevents the overhead of having to reparse if XStream is working from
        XML that has been partially processed by other libraries (for instance a SOAP library). It also avoids tying XStream
        to a particular library.</p>

        <p>XStream comes bundled with
        <a href="javadoc/com/thoughtworks/xstream/io/xml/package-summary.html">reader and writer implementations</a> for
        most major XML libraries.</p>

        <p class="highlight">Writer and Readers can be implemented allowing XStream to serialize to most XML APIs.
        Writers and Readers can also be created around tree based non XML structures.</p>

        <!--
            note: one reader/writer per context
            note: why not sax
        -->

        <!-- ************ -->

        <h1 id="Context">Context</h1>

        <p>When XStream serializes or deserializes some objects, it creates a
        <a href="javadoc/com/thoughtworks/xstream/converters/MarshallingContext.html">MarshallingContext</a> or
        <a href="javadoc/com/thoughtworks/xstream/converters/UnmarshallingContext">UnmarshallingContext</a>,
        which handle the traversing of the data and delegation to the necessary Converters.</p>

        <p class="highlight">The MarshallingContext/UnmarshallingContext is made available to converters allowing them
        to tell XStream to process objects contained within other objects.</p>

        <p>XStream provides three pairs of context implementations that traverse the object graph with slightly
        different behaviors. The default can be changed using
        <a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream.setMode()</a>, passing in one of
        the following parameters:</p>

        <ul>
            <li>
                <b>XStream.XPATH_RELATIVE_REFERENCES</b><br/>
                <i>(Default)</i> Uses relative XPath references to signify duplicate references. This produces XML with 
                the least clutter.
            </li>
            <li>
                <b>XStream.XPATH_ABSOLUTE_REFERENCES</b><br/>
                Uses absolute XPath references to signify duplicate references. This might produce for some situations
                better readable XML. <i>Note, that XStream will read XML with relative paths as well as with absolute
                paths independent of the XPATH mode.</i>
            </li>
            <li>
                <b>XStream.ID_REFERENCES</b><br/>
                Uses ID references to signify duplicate references. In some scenarios, such as when using hand-written
                XML, this is easier to work with.
            </li>
            <li>
                <b>XStream.NO_REFERENCES</b><br/>
                This disables object graph support and treats the object structure like a tree. Duplicate references are
                treated as two separate objects and circular references cause an exception. This is slightly faster and
                uses less memory than the other two modes.
            </li>
        </ul>

        <p class="highlight">A new context is created for each object graph that is serialized. Both the
        <a href="javadoc/com/thoughtworks/xstream/converters/MarshallingContext.html">MarshallingContext</a> and
        <a href="javadoc/com/thoughtworks/xstream/converters/UnmarshallingContext.html">UnmarshallingContext</a>
        implement <a href="javadoc/com/thoughtworks/xstream/converters/DataHolder.html">DataHolder</a>,
        a hash table passed around whilst processing the object graph that can be used as the user sees fit (in a similar
        way that the HttpServletRequest attributes are used in a web-application).</p>

        <!-- ************ -->

        <h1 id="TypePermissions">Type Permissions</h1>

        <p>XStream's  <a href="security.html#framework">Security Framework</a> consists of a Mapper implementation and
        a lot of <a href="javadoc/com/thoughtworks/xstream/security/TypePermission.html">type permissions</a>.  These
        implementations are used to deny or allow the deserialization of java types based on their name or type
        hierarchy.</p>

        <!-- ************ -->

        <h1 id="Facade">XStream facade</h1>

        <p>The main <a href="javadoc/com/thoughtworks/xstream/XStream.html">XStream</a> class is typically used as the
        entry point. This assembles the necessary components of XStream (as described above; Context, Converter,
        Writer/Reader and ClassMapper) and provides a simple to use API for common operations.</p>

        <p class="highlight">Remember, the XStream class is just a facade - it can always be bypassed for more advanced
        operations.</p>

    </body>
</html>